Skip to content

docs(react,angular): use ionPage prop for nested outlets and add navigation playgrounds#4454

Merged
ShaneK merged 17 commits intomajor-9.0from
v9/react-router-2183
Mar 31, 2026
Merged

docs(react,angular): use ionPage prop for nested outlets and add navigation playgrounds#4454
ShaneK merged 17 commits intomajor-9.0from
v9/react-router-2183

Conversation

@ShaneK
Copy link
Copy Markdown
Member

@ShaneK ShaneK commented Mar 30, 2026

Resolves #2183

Description

Currently, several examples for using React Router are incorrectly showing wrapping IonRouter with IonPage instead of using the ionPage prop. Additionally, React and Angular have hard-coded links to StackBlitz that we do not control and have since moved away from in favor of playgrounds.

This PR does multiple things:

  • Fixes React Router demonstrations
  • Removes direct extremely outdated StackBlitz "Live Examples" in favor of Playgrounds

Change Type

  • Fix
  • Feature
  • Refactor
  • Breaking Change
  • Documentation

Examples

Angular Navigation/Routing - Live Example

React Navigation/Routing - Should no longer have IonPage wrapping IonRouter and should use the ionPage prop instead. Additionally, stackblitz link under Live Example swapped for Playground

@ShaneK ShaneK requested a review from a team as a code owner March 30, 2026 12:22
@ShaneK ShaneK requested review from brandyscarney and removed request for a team March 30, 2026 12:22
@vercel
Copy link
Copy Markdown

vercel bot commented Mar 30, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
ionic-docs Ready Ready Preview, Comment Mar 31, 2026 3:46pm

Request Review

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than putting these under separate angular and react folders should we do one playground with both frameworks? Structure:

static
└── usage
    └── v9
        └── navigation
            ├── angular
            │   ├── app_component_html.md
            │   ├── app_component_ts.md
            │   ├── app_routes_ts.md
            │   ├── dashboard_page_component_html.md
            │   ├── dashboard_page_component_ts.md
            │   ├── example_component_html.md
            │   ├── example_component_ts.md
            │   ├── item_detail_page_component_html.md
            │   ├── item_detail_page_component_ts.md
            │   ├── settings_page_component_html.md
            │   └── settings_page_component_ts.md
            ├── react
            │   ├── dashboard_page_tsx.md
            │   ├── item_detail_page_tsx.md
            │   ├── main_tsx.md
            │   └── settings_page_tsx.md    
            ├── demo.html
            └── index.md

This would allow us to add a JavaScript and Vue one if we would like.

Copy link
Copy Markdown
Member Author

@ShaneK ShaneK Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the reason was we couldn't previously is because then the React playground would show the Angular playground by default (unless you happened to have selected React from a component view before, in which case Angular would have shown React by default), which is a bad UX.

This inspired me to fix this, though, so in this commit (de72886) I added support for default frameworks and made the React and Angular pages use it, most of the work for combining them was done in this commit though (58873e4)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! What if we had two separate index.md files and just imported the one we wanted? Right now it shows both are enabled but you can't click on the other one:

CleanShot 2026-03-31 at 09 40 03@2x

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Welp, that was a bug. Fixed that here: 91f7811

I actually like one unified playground where they can swap between the two if they want to see how it works in other frameworks for comparison

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is what I was thinking, feel free to edit: 785d345

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ohh, I was misunderstanding. Nice, that's awesome!

);
};
const DashboardPage: React.FC = () => (
<IonRouterOutlet ionPage>
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand why ionPage is now required. We have never recommended adding this as a property and it is not added to any of the playgrounds.

Copy link
Copy Markdown
Member Author

@ShaneK ShaneK Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's never been recommended because the docs have been known to be wrongly recommending wrapping IonRouterOutlet in IonPages for several years and nobody has fixed it (note the age of the issue this resolves).

Using the ionPage prop on the router outlet directly benefits mostly nested routes (it's required by them, technically). When you have an outlet containing routes and one of those routes renders another outlet, like in a tab layout, the inner outlet needs to know about and be able to participate in the outer outlet's page transitions. Setting the prop makes the inner outlet itself the animatable page element, so the outer StackManager can transition it properly.

It's generally best to do this everywhere so you don't have to remember to do it in the special nested routing edge cases, and that will also be the case in RR6.

Copy link
Copy Markdown
Member

@brandyscarney brandyscarney left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good!

@ShaneK ShaneK merged commit fbf2799 into major-9.0 Mar 31, 2026
4 checks passed
@ShaneK ShaneK deleted the v9/react-router-2183 branch March 31, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants